update diag_manager documentation by rem1776 · Pull Request #1869 · NOAA-GFDL/FMS

rem1776 · 2026-05-06T20:57:24Z

Description
Updates the diag_manager documentation.

I tried to incorporate more information about which code is rewritten vs legacy code.

How Has This Been Tested?
n/a

Checklist:

My code follows the style guidelines of this project
I have performed a self-review of my own code
I have commented my code, particularly in hard-to-understand areas
I have made corresponding changes to the documentation
My changes generate no new warnings
Any dependent changes have been merged and published in downstream modules
New check tests, if applicable, are included
make distcheck passes

Co-authored-by: Ryan Mulhall <35538242+rem1776@users.noreply.github.com>

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR primarily improves documentation and Doxygen grouping across the legacy/modern diag_manager code, adds dedicated namelist documentation, and makes a small error-message correction for consistency.

Changes:

Expanded/clarified module headers and added “legacy vs modern diag_manager” notes across multiple Fortran modules.
Added new diag_manager_nml Markdown documentation.
Minor message/documentation cleanups (e.g., updated fatal error prefix for fms_get_domain2d).

Reviewed changes

Copilot reviewed 18 out of 19 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
diag_manager/fms_diag_yaml.F90	Updated module brief to describe YAML object + read routines.
diag_manager/fms_diag_reduction_methods.F90	Expanded module documentation; added debug-flag instructions.
diag_manager/fms_diag_output_buffer.F90	Added Doxygen group annotations and clarified module brief.
diag_manager/fms_diag_outfield.F90	Marked as legacy module and pointed to modern equivalents.
diag_manager/fms_diag_object.F90	Corrected fatal error message to the right module/function name.
diag_manager/fms_diag_input_buffer.F90	Clarified purpose (OpenMP/threaded send_data buffering).
diag_manager/fms_diag_file_object.F90	Improved Doxygen docs for modern file-object module and type fields.
diag_manager/fms_diag_fieldbuff_update.F90	Marked as legacy module and pointed to modern equivalents.
diag_manager/fms_diag_field_object.F90	Added richer Doxygen groups/docs for modern field object module/type.
diag_manager/fms_diag_bbox.F90	Minor documentation/formatting cleanup in bbox module.
diag_manager/fms_diag_axis_object.F90	Significantly expanded axis/domain documentation and comments.
diag_manager/diag_util.F90	Added legacy note; removed obsolete commented “FUTURE” block.
diag_manager/diag_table.F90	Added legacy note pointing to modern YAML/object path.
diag_manager/diag_output.F90	Added legacy note pointing to modern I/O/object path.
diag_manager/diag_manager_nml.md	New: Markdown documentation for `diag_manager_nml` variables.
diag_manager/diag_manager.F90	Expanded top-level module documentation and removed embedded namelist block.
diag_manager/diag_grid.F90	Added legacy note with a callout that one routine is still used by modern path.
diag_manager/diag_axis.F90	Added legacy note explaining modern routing behavior.
diag_manager/README.md	Major expansion/restructure describing rewrite and YAML examples.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

  !> @addtogroup fms_diag_yaml_mod
  !> @{
  contains


 public :: fmsDiagFileContainer_type
 public :: fmsDiagFile_type, fms_diag_files_object_init, fms_diag_files_object_initialized
+!> @}
+

 logical :: fms_diag_files_object_initialized = .false.


+!! @brief fms_diag_reduction_methods_mod contains routines that are used to perform diagnostic reduction methods,
+!! such as max/min, average, rms, etc. These routines are called by the send_data routines in the diag_manager.
+!!
+!! To debug the reduction methods, compile with `-DFMS_DIAG_DEBUG_REDUCT=.true.` and the reduction routines will print
+!! out the values of the buffer and field data at each time step.


+!! @note This file is part of the legacy diag_manager.
+!! If use_modern_diag is enabled, this module will be unused, as all IO will be handled
+!! by the fms_diag_object.F90 module and it's helpers.


 The modern diag manager uses a YAML format instead of the legacy ascii table. A description of the YAML diag table can
 be found [here](diag_yaml_format.md). A formal specification, in the form of a JSON schema, can be found in the
 [gfdl_msd_schemas](https://github.com/NOAA-GFDL/gfdl_msd_schemas) repository on Github.


+  varlist:
+  - var_name: var1
+    output_name: variable_one
+	reduction: average


uramirez8707 · 2026-06-03T17:47:48Z

+### `use_mpp_io`
+- Type: `LOGICAL`
+- Default: `.FALSE.`
+- Description: Selects the I/O backend: true uses `mpp_io`, false uses `fms2_io` (recommended).


This is not going to be an option after resolving #1881

mlee03 · 2026-06-03T17:58:12Z

 !! @brief diag_manager_mod is a set of simple calls for parallel diagnostics
 !!   on distributed systems. It is geared toward the writing of data in netCDF
-!!   format. See @ref diag_manager for diag table information.
+!!   format. The diag_manager differs from the fms2_io module in that it reads in


Below is not perfect, but perhaps better organized than what's here?

Diag_manager consists of tools for handling diagnostic variables in parallel on distributed systems. It uses fms2_io under the hood to write the data in NetCDF format.

Diag_manager uses the diag_table to read in all user-defined diagnostic specifications such as [fill me in with stuff like file name, write frequencies,]. This module also handles 'reduction' operations such as taking the averaging or taking the min/max of the data. [link to all reduction methods]. For example, users can send_data for a field multiple times for a timestep and the output will be 'reduced' as specified in the diag_table.

mlee03 · 2026-06-03T18:00:22Z

+!!   The modern diag manager is enabled via the <TT>use_modern_diag</TT> flag in the <TT>diag_manager_nml</TT>
+!!   namelist. By default, the legacy diag manager is used to maintain backward compatibility. When
+!!   <TT>use_modern_diag = .true.</TT>, the modern implementation is used while maintaining the same public interfaces.
+!!   FMS must be built with libyaml support via the <TT>-Duse_yaml</TT> flag to use the modern diag manager.


for example, send_data remains the same in the modern and legacy diag_manager

mlee03 · 2026-06-03T18:00:54Z

  END INTERFACE

-  !> @brief Register a diagnostic field for a given module
+  !> @brief Register a diagnostic field for a given module, this is equivalent to creating a


mlee03 · 2026-06-03T18:03:32Z

+
+The `diag_manager_nml` namelist contains runtime configuration options for the diagnostic manager.
+
+Although the namelist is defined in `diag_manager_mod`, all variables belong to the `diag_data_mod` module.


See diag_data_mod for details

mlee03 · 2026-06-03T18:04:12Z

+### `append_pelist_name`
+- Type: `LOGICAL`
+- Default: `.FALSE.`
+- Description: If true, appends the processor element list name to output filenames. Useful for distinguishing output files from different processor configurations.


Is there an example of what the filename will look like?

mlee03 · 2026-06-03T18:27:06Z

+  - is_a_file: true
+```
+
+### 3. Scalar Axis


The old diag_manager adds a scalar_axis ...

mlee03 · 2026-06-03T18:28:03Z

@@ -27,7 +168,7 @@ variables:
 ```
 The new diag manager will no longer have a dummy scalar axis dimension.


The new diag manager no longer adds a dummy scalar axis dimension

mlee03 · 2026-06-03T18:29:15Z

+### 5. Subregional Files

 #### A. `is_subregional` global attribute:
 Subregional files will have a global NetCDF attribute `is_subregional = True` set for non-global history files. This attribute will be used in PP tools.


PP tools from fre?

mlee03 · 2026-06-03T18:30:24Z

@@ -80,7 +221,7 @@ In some cases, the old diag manager was adding `sub0X` to the dimension names wh
 #### C. Corner and center diagnostics:
 In the old diag manager, if mixing variables that are corner variables, such as velocities={uo,vo,umo,vmo} and center variables, such as tracers={thetao,so,volcello} you sometimes ended up with a different number of variables per file. The extra files had duplicate data for the corner velocities because the two PEs shared the point at the edge. This happened with some grid/layouts/masks/subregion combinations and it caused problems with the combiner. The new diag manager will not have this problem.


This is not clear..

mlee03 · 2026-06-03T18:33:27Z

+!! It provides helper methods for field registration, data buffering, metadata queries,
+!! and NetCDF I/O support used by the diag_manager.
+!!
+!! The diagnostic field object is the central representation of a variable in


central representation => holds the main information or something like that?

or maybe this paragraph isn't needed since it's explained later

Co-authored-by: uramirez8707 <49168881+uramirez8707@users.noreply.github.com>

rem1776 added 6 commits May 6, 2026 15:17

update legacy modules with note and do some cleanup

f10392f

fix modern/legacy file list in readme

bd753c8

revert variable deletion

d15f5f3

fix bad info in main module description

e90b74e

clean up for diag_axis_object

e171138

update descriptions for field and file objs

c5c8679

rem1776 commented May 7, 2026

View reviewed changes

rem1776 added 2 commits May 12, 2026 12:18

Update diag_manager/fms_diag_axis_object.F90

a806f09

Update diag_manager/fms_diag_axis_object.F90

3b8ed42

rem1776 commented May 13, 2026

View reviewed changes

Comment thread diag_manager/include/fms_diag_reduction_methods.inc Outdated

rem1776 commented May 13, 2026

View reviewed changes

Comment thread diag_manager/include/fms_diag_reduction_methods.inc Outdated

rem1776 and others added 6 commits May 13, 2026 11:20

Apply suggestions from code review

036f0ea

Co-authored-by: Ryan Mulhall <35538242+rem1776@users.noreply.github.com>

add changes from review

43acd72

Merge branch 'diag-docz' of github.com:rem1776/fms into diag-docz

e5e2790

fix line lengths and build issues

dc60b76

update readme with examples

5a2272a

linter!

41fde4e

rem1776 marked this pull request as ready for review May 19, 2026 16:33

rem1776 requested review from bensonr, uramirez8707 and vithikashah001 as code owners May 19, 2026 16:33

mlee03 requested a review from Copilot June 3, 2026 18:01

Copilot AI reviewed Jun 3, 2026

View reviewed changes

uramirez8707 requested changes Jun 3, 2026

View reviewed changes

mlee03 suggested changes Jun 3, 2026

View reviewed changes

rem1776 and others added 2 commits June 3, 2026 15:05

take out unused macro

237cb59

Apply Uriel's suggestions from code review

98b8889

Co-authored-by: uramirez8707 <49168881+uramirez8707@users.noreply.github.com>


		The `diag_manager_nml` namelist contains runtime configuration options for the diagnostic manager.

		Although the namelist is defined in `diag_manager_mod`, all variables belong to the `diag_data_mod` module.

		@@ -27,7 +168,7 @@ variables:
		```
		The new diag manager will no longer have a dummy scalar axis dimension.

		@@ -80,7 +221,7 @@ In some cases, the old diag manager was adding `sub0X` to the dimension names wh
		#### C. Corner and center diagnostics:
		In the old diag manager, if mixing variables that are corner variables, such as velocities={uo,vo,umo,vmo} and center variables, such as tracers={thetao,so,volcello} you sometimes ended up with a different number of variables per file. The extra files had duplicate data for the corner velocities because the two PEs shared the point at the edge. This happened with some grid/layouts/masks/subregion combinations and it caused problems with the combiner. The new diag manager will not have this problem.

Conversation

rem1776 commented May 6, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants